import ThemedImage from "@theme/ThemedImage";

# Environments

The Rig Platform supports a multi-environment architecture out-of-the-box. All Capsules in the Platform are
automatically deployable to all environments. That means a single Environment always contains some sub-set of all Platform Capsules.

Each environment has its own configuration of a given Capsule. Capsule A can e.g. have 10 replicas in `production` but only 2 in `staging`.

<ThemedImage
  alt="Topology"
  customProps={{
    zoom: false,
  }}
  sources={{
    light: "/img/operator-manual/environment/topology.png",
    dark: "/img/operator-manual/environment/topology.png",
  }}
/>

In this example, changes made to Capsules in Environment B are not reflected to Capsules in Environment A, and vice-versa.

## Creating new environments

To create a new environment, use the following CLI command:

```bash
rig env create my-environment my-cluster
```

The newly created environment is immediately available for existing Capsules as a deployment target:

```bash
rig deploy -E my-environment my-capsule --image nginx
```

### Custom namespace templating

By default, namespaces in the new environment will be named after the project. To change this,
a custom namespace template can be provided:

```bash
rig env create my-environment my-cluster \
  --namespace-template '{{ .Project.Name }}-{{ .Environment.Name }}'
```

This example will suffix all namespaces with the environment, allowing multiple environments in a single
cluster.

the following template variables are available:
- `.Project.Name`: The name of the project
- `.Environment.Name`: The name of the environment

## Deleting environments

An environment can be deleted with a simple command;

```bash
rig env delete my-environment
```

However, if any Capsules is currently running in the environment, the operation will abort. Use `--force` to override this behavior.

:::warning Force deletion
Force deletion an environment will stop *all* running Capsules in that environment. Use this flag with care.
:::


## Ephemeral environments

Ephemeral environments are short-lived environments often used in a CI/CD context for testing purposes.
Due to the flexible nature of environments, it's very straight forward to implement ephemeral environments with Rig.

The following steps are easily implemented in any CI/CD systems, such as GitHub Actions, GitLab or Circle CI:

1. First, the new environment should be created. This can be based on the pull-request ID, branch-name or something else:

    ```bash
    rig env create "temp-env-$BRANCH_NAME" testing-cluster \
      --namespace-template '{{ .Project.Name }}-{{ .Environment.Name }}'
    ```

2. Next, all capsules that should be running in this environment should be deployed:

    ```bash
    rig deploy -E "temp-env-$BRANCH_NAME" -P my-project my-capsule1 --image nginx
    rig deploy -E "temp-env-$BRANCH_NAME" -P my-project my-capsule2 --image nginx
    ```

3. Finally, when the environment is no longer used, e.g. when a pull-request is closed, the environment can be deleted:

    ```bash
    rig env delete "temp-env-$BRANCH_NAME" --force
    ```

## Multi-Cluster setup using Environments

Environments are associated to a single cluster, meaning Rig supports multiple clusters
through environments.

Multiple environments can also exist in a single cluster (useful for ephemeral environments), meaning
any mix and match of environments and clusters are possible:

<ThemedImage
  alt="Topology"
  customProps={{
    zoom: false,
  }}
  sources={{
    light: "/img/operator-manual/environment/multi-cluster.png",
    dark: "/img/operator-manual/environment/multi-cluster.png",
  }}
/>

Here two production-clusters each have a single environment, while a staging has a number of testing environments.

:::info unique namespaces
When having multiple environments in a single cluster, it's important to ensure the namespace template generated unique
namespaces, preferable by having the environments as part of the namespace name.
